home *** CD-ROM | disk | FTP | other *** search
/ The 640 MEG Shareware Studio 4 / The 640 Meg Shareware Studio CD-ROM Volume IV (Data Express)(1994).ISO / clang / xlib05.zip / XLIBREF2.DOC < prev    next >
Text File  |  1993-08-27  |  29KB  |  866 lines
  1. PART 2 of 2
  2. -----------------------------------------------------------------------------
  3.  
  4.   *********      XLIB - Mode X graphics library           ****************
  5.   *********                                               ****************
  6.   ********* Written By Themie Gouthas                     ****************
  7.   *********                                               ****************
  8.   ********* egg@dstos3.dsto.gov.au                        ****************
  9.   ********* teg@bart.dsto.gov.au                          ****************
  10.  
  11.       Some of the code in this library has been contributed by :
  12.  
  13.            Matthew MacKenzie - matm@eng.umd.edu
  14.  
  15.   Notes:
  16.     References to my employer have been removed as this library is my
  17.     own intellectual property, developed solely in my own time.
  18.  
  19.     I informally reserve all rights to the code in XLIB.
  20. -----------------------------------------------------------------------------
  21. MODULE  XCLIPPBM   note: VERY SIMILAR to XPBMCLIP
  22. This module implements blits of clipped planar bitmaps.  Blits are
  23. clipped to pixels, both horizontally.  This makes the unmasked blit
  24. function here slightly slower than the equivalent functions in the
  25. XPBMCLIP module.
  26. --------------------------------------------------------------------------
  27.                                  XCLIPPBM:
  28.                              Blits and Pieces
  29.                            by Matthew MacKenzie
  30.  
  31. The XCLIPPBM module contains clipping versions of two of the three routines
  32. in the XPBITMAP module:
  33.   o  x_clip_pbm transfers a planar bitmap to the screen, clipping off any
  34.      part outside a bounding box.
  35.   o  x_clip_masked_pbm does the same thing, but transfers only nonzero
  36.      pixels.
  37.  
  38.     The planar bitmap format is described elsewhere.  Here we will look at
  39. the clipping itself, since it is the only distinguishing feature of this
  40. module.
  41.     The bounding box is made up of four integers, TopBound, BottomBound,
  42. LeftBound, and RightBound.  Unlike most global variables in Xlib, these are
  43. meant to be written to.  In fact, they start out uninitialized.  Be sure to
  44. set them before you try plotting any clipped bitmaps.
  45.     Note that these are not the same variables which are used in the other
  46. clipping modules in Xlib.  This is because the two systems are incompatible:
  47. the other modules clip horizontally to columns while this one clips to
  48. pixels.  As you might have guessed, those functions and these were developed
  49. in different hemispheres of the planet...
  50.     If it's any consolation, this does give you two independent
  51. bounding boxes to futz with, should the mood visit you.
  52.     Bitmaps cannot go outside the perimeter of the bounding box, but they
  53. can overlap it.  If TopBound equals BottomBound, for example, a horizontal
  54. slice of a bitmap may still be plotted.  It is safe to turn the box "inside
  55. out" to make sure nothing will be plotted -- this is the first thing each
  56. routine checks for.
  57.     To plot a bitmap, minus its zero pixels, minus anything outside the
  58. bounding box:
  59.  
  60. x_clip_masked_pbm (int X, int Y, int ScreenOffs, char far * Bitmap);
  61.  
  62.     The arguments are in the same order as those for x_put_masked_pbm in
  63. the module XPBITMAP.  The bounding box is relative to the given
  64. ScreenOffs(et).  This lets you perform page flipping without worrying about
  65. what screen you are clipping to -- it's always the current screen.  The
  66. bitmap itself, of course, is not affected; clipping is performed on-the-
  67. fly.  Both functions return an integer which indicates whether any part
  68. of the bitmap was inside the bounding box.  If the entire bitmap was
  69. outside, a 1 is returned; otherwise, a 0.
  70.     The third function in XPBITMAP, for which this module has no
  71. equivalent, copies from video RAM to system RAM.  The absence of such a
  72. routine may seem at first like a disadvantage -- but this, like so many
  73. things in this life, is an illusion.  You can use the unclipped routine,
  74. and clip the bitmap when you want to plot it back onto the screen.
  75.  
  76.   ASM SOURCES
  77.  
  78.      xclippbm.asm xclippbm.inc xlib.inc model.inc
  79.  
  80.   C HEADER FILE
  81.  
  82.      xclippbm.h
  83.  
  84.   EXPORTED VARIABLES
  85.  
  86.   TopBound - int
  87.   BottomBound - int
  88.   LeftBound - int
  89.   RightBound - int
  90.  
  91.   EXPORTED FUNCTIONS
  92.  
  93.   x_clip_pbm
  94.   ----------
  95.   C Prototype: extern int x_clip_pbm (int X, int Y, int ScreenOffs, char
  96.                                        far * Bitmap);
  97.  
  98.   Copies a planar bitmap from SRAM to VRAM, with clipping.  If the entire
  99.   bitmap turns out to be outside the bounding box, this function returns
  100.   a 1; otherwise it returns a 0.
  101.  
  102.   x_clip_masked_pbm
  103.   -----------------
  104.   C Prototype: extern int x_clip_masked_pbm (int X, int Y,
  105.                                    int ScreenOffs, char far * Bitmap);
  106.  
  107.   Copies a planar bitmap from SRAM to VRAM, with clipping -- 0 bytes
  108.   in the bitmap are not copied.  If the entire bitmap turns out to be
  109.   outside the bounding box, this function returns a 1; otherwise,
  110.   it returns a 0.
  111.  
  112.  
  113. --------------------------------------------------------------------------
  114. MODULE  XMOUSE
  115. --------------------------------------------------------------------------
  116. The XMOUSE module implements very basic mouse handling functions. The way
  117. in which it operates is by installing an event handler function during
  118. initialization which subsequently intercepts and processes mouse events and
  119. automatically updates status variables such as mouse position and button
  120. pressed status. It does not support the full functionality of:
  121.  
  122.   SPLIT SCREENS
  123.   SCROLLED WINDOWS
  124.   VIRTUAL WINDOWS
  125.  
  126. This was done to primarily prevent unecessary impedences to performance,
  127. since the mouse handler function has the potential to degrade performance.
  128. It also saves me alot of coding which I was too lazy to do.
  129.  
  130. Programs communicate with the mouse driver as with other devices, through
  131. an interrupt vector namely 33h. On generating an interrupt, the mouse driver
  132. expects a function number in AX and possibly other parameters in other
  133. registers and returns information via the registers. A brief description
  134. of the mouse functions follows:
  135.  
  136.           --------------------------------------
  137.  
  138.           MS Mouse Driver Functions
  139.  
  140.           Mouse Initialization                 0
  141.           Show Cursor                          1
  142.           Hide Cursor                          2
  143.           Get Mouse Position & Button Status   3
  144.           Set Mouse Cursor Position            4
  145.           Get Button Press Information         5
  146.           Get Button Release Information       6
  147.           Set Min/Max Horizontal Position      7
  148.           Set Min/Max Vertical Position        8
  149.           Define Graphics Cursor Block         9
  150.           Define Text Cursor                  10
  151.           Read Mouse Motion Counters          11
  152.           Define Event Handler                12
  153.           Light Pen Emulation Mode ON         13
  154.           Light Pen Emulation Mode OFF        14
  155.           Set Mouse Mickey/Pixel Ratio        15
  156.           Conditional Hide Cursor             16
  157.           Set Double-Speed Threshold          19
  158.           --------------------------------------
  159.  
  160. In practice only afew of these functions are used and even fewer when the
  161. mouse status is monitored by an event handler function such as is used in
  162. this module.
  163.  
  164. The most important thing to note when using the mouse module is that the
  165. mouse event handler must be removed before exiting the program. It is a good
  166. idea to have an exit function (see the C "atexit" function) and include the
  167. line "x_mouse_remove();" along with any other pre-exit cleanup code.
  168.  
  169. See also: XDETECT for mouse detection.
  170.  
  171.   ASM SOURCES
  172.  
  173.     xmouse.asm xlib.inc model.inc
  174.  
  175.   C HEADER FILE
  176.  
  177.     xmouse.h
  178.  
  179.   EXPORTED VARIABLES
  180.  
  181.    MouseInstalled    - WORD - Indicates whether mouse handler installed
  182.    MouseHidden       - WORD - Indicates whether mouse cursor is hidden
  183.    MouseButtonStatus - WORD - Holds the mouse button status
  184.    MouseX            - WORD - Current X position of mouse cursor
  185.    MouseY            - WORD - Current Y position of mouse cursor
  186.    MouseFrozen       - WORD - Disallows position updates if TRUE
  187.    MouseColor        - BYTE - The mouse cursors colour
  188.  
  189.   EXPORTED FUNCTIONS
  190.  
  191.   x_mouse_init
  192.   ------------
  193.  
  194.     C Prototype:  int x_mouse_init()
  195.  
  196.   Initialize the mouse driver functions and install the mouse event handler
  197.   function. This is the first function you must call before using any of the
  198.   mouse functions. This mouse code uses the fastest possible techniques to
  199.   save and restore mouse backgrounds and to draw the mouse cursor.
  200.  
  201.   WARNING: This function uses and updates "NonVisual_Offset" to allocate
  202.        video ram for the saved mouse background.
  203.  
  204.   LIMITATIONS: No clipping is supported horizontally for the mouse cursor
  205.            No validity checking is performed for NonVisual_Offs
  206.  
  207.   **WARNING** You must Hide or at least Freeze the mouse cursor while drawing
  208.           using any of the other XLIB modules since the mouse handler may
  209.           modify vga register settings at any time. VGA register settings
  210.           are not preserved which will result in unpredictable drawing
  211.           behavior. If you know the drawing will occur away from the
  212.           mouse cursor set MouseFrozen to TRUE (1), do your drawing
  213.           then set it to FALSE (0). Alternatively call "x_hide_mouse",
  214.           perform your drawing and then call "x_show_mouse". Another
  215.           alternative is to disable interrupts while drawing but usually
  216.           drawing takes up alot of time and having interrupts disabled
  217.           for too long is not a good idea.
  218.  
  219.   x_define_mouse_cursor
  220.   ---------------------
  221.  
  222.   C Prototype:
  223.     void x_define_mouse_cursor(char far *MouseDef, unsigned char MouseColor)
  224.  
  225.     MouseDef - a pointer to 14 characters containing a bitmask for all the
  226.            cursor's rows.
  227.     MouseColor - The colour to use when drawing the mouse cursor.
  228.  
  229.   Define a mouse cursor shape for use in subsequent cursor redraws. XMouse
  230.   has a hardwired mouse cursor size of 8 pixels across by 14 pixels down.
  231.  
  232.   WARNING: This function assumes MouseDef points to 14 bytes.
  233.  
  234.   Note: Bit order is in reverse. ie bit 7 represents pixel 0 ..
  235.     bit 0 represents pixel 7 in each "MouseDef" byte.
  236.  
  237.   x_show_mouse
  238.   ------------
  239.  
  240.   C Prototype:  void x_show_mouse()
  241.  
  242.   Makes the cursor visible if it was previously hidden.
  243.   See Also: "x_hide_mouse".
  244.  
  245.   x_hide_mouse
  246.   ------------
  247.  
  248.   C Prototype:  void x_hide_mouse()
  249.  
  250.   Makes the cursor hidden if it was previously visible.
  251.   See Also: "x_show_mouse".
  252.  
  253.   x_remove_mouse
  254.   --------------
  255.  
  256.   C Prototype:  void x_remove_mouse()
  257.  
  258.   Stop mouse event handling and remove the mouse handler.
  259.  
  260.   NOTE: This function MUST be called before quitting the program if
  261.        a mouse handler has been installed
  262.  
  263.   x_position_mouse
  264.   ----------------
  265.  
  266.   C Prototype  void x_position_mouse(int x, int y)
  267.  
  268.   Positions the mouse cursor at the specified location
  269.  
  270.   x_update_mouse
  271.   --------------
  272.  
  273.   C Prototype:  void x_update_mouse()
  274.  
  275.   Forces the mouse position to be updated and cursor to be redrawn.
  276.   Note: this function is useful when you have set "MouseFrozen" to true.
  277.   Allows the cursor position to be updated manually rather than
  278.   automatically by the installed handler.
  279.  
  280. --------------------------------------------------------------------------
  281. MODULE  XCIRCLE
  282. --------------------------------------------------------------------------
  283.                 XCIRCLE:
  284.               Wheel Have to See About That
  285.              by Matthew MacKenzie
  286.  
  287. The XCIRCLE module contains two functions, neither of which should be
  288. a big mystery:
  289.   o  x_circle, oddly enough, draws a circle.
  290.   o  x_filled_circle does too, only the circle is filled (in some
  291.      libraries this is called a disc).
  292.  
  293.     The word `circle' here refers to a round thing which is as many
  294. pixels tall as across.  It only looks like a circle in 320x240 mode --
  295. the original mode X -- and in 376x282 mode.
  296.     In both functions, the circle is specified by the coordinates of the
  297. upper-left-hand corner of the smallest box which holds it, and the
  298. diameter.  Some circle functions have you specify a center point;
  299. this system is kind of odd because a circle with an even diameter does
  300. not have a particular pixel for a center.  Every circle, on the other
  301. hand, has a box with an upper-left corner.
  302.     No bounds are checked.  A diameter of zero will draw nothing, and
  303. a negative diameter will blow your VGA board into hundreds of thousands
  304. of tiny little smoldering fragments.  Neither function supports clipping.
  305.     The calculation of the circle is based on an algorithm described
  306. by Michael P. Lindner in a letter to the editor on page 8 of Dr. Dobb's
  307. Journal #169 (October 1990).  The algorithm has been rearranged to
  308. allow drawing and moving the plots in the eight octants to be performed
  309. in one step, so that each pixel does not have to be loaded into the CPU
  310. twice.  x_filled_circle does not take advantage of this optimization
  311. because it handles different parts of each plot at different times.
  312.  
  313.   ASM SOURCES
  314.  
  315.   xcircle.asm xcircle.inc xlib.inc model.inc
  316.  
  317.   C HEADER FILE
  318.  
  319.   xcircle.h
  320.  
  321.   EXPORTED FUNCTIONS
  322.  
  323.   x_circle
  324.   --------
  325.   C Prototype: extern void x_circle (WORD Left, WORD Top, WORD Diameter,
  326.                      WORD Color, WORD ScreenOffs);
  327.  
  328.   Draws a circle with the given upper-left-hand corner and diameter,
  329.   which are given in pixels.
  330.  
  331.  
  332.   x_filled_circle
  333.   ---------------
  334.   C Prototype: extern void x_filled_circle (WORD Left, WORD Top,
  335.                 WORD Diameter, WORD Color, WORD ScreenOffs);
  336.  
  337.   Draws a filled circle with the given upper-left-hand corner and
  338.   diameter.
  339.  
  340.  
  341. --------------------------------------------------------------------------
  342. MODULE XDETECT
  343. --------------------------------------------------------------------------
  344.  
  345.   This module implements a set of functions to detect the PC's hardware
  346.   configuration.
  347.  
  348.   ASM SOURCES
  349.  
  350.     xdetect.asm xdetect.inc model.inc
  351.  
  352.   C HEADER FILE
  353.  
  354.     xdetect.h
  355.  
  356.   EXPORTED MACROS
  357.  
  358.     I8086   0
  359.     I80186  1
  360.     I80286  2
  361.     I80386  3
  362.  
  363.     NoGraphics 0
  364.     MDA        1
  365.     CGA        2
  366.     EGAMono    3
  367.     EGAColor   4
  368.     VGAMono    5
  369.     VGAColor   6
  370.     MCGAMono   7
  371.     MCGAColor  8
  372.  
  373.     BUS_MOUSE     1
  374.     SERIAL_MOUSE  2
  375.     INPORT_MOUSE  3
  376.     PS2_MOUSE     4
  377.     HP_MOUSE      5
  378.  
  379.  
  380.   EXPORT VARIABLES
  381.  
  382.   MouseButtonCount  - WORD - The number of buttons on the detected mouse
  383.   MouseVersion      - WORD - Mouse driver version (High byte = Major version
  384.                  Low byte = minor version)
  385.   MouseType         - BYTE - The mouse type
  386.   MouseIRQ          - BYTE - The IRQ number used by the mouse driver
  387.  
  388.   EXPORT FUNCTIONS
  389.  
  390.  
  391.   x_graphics_card
  392.   ---------------
  393.   C Prototype: extern int x_graphics_card();
  394.  
  395.   This function returns the type of graphics card installed. See defines
  396.   above.
  397.  
  398.   x_processor
  399.   -----------
  400.   C Prototype: extern int x_processor();
  401.  
  402.   This function returns the type of processor installed. A 486 registers
  403.   as a 386. See defines above.
  404.  
  405.   x_coprocessor
  406.   -------------
  407.   C Prototype: extern int x_coprocessor();
  408.  
  409.   This function returns 1 of a numeric co-processor is present, 0 if not.
  410.   The type is not detected but it's mnot really necessary as the processor
  411.   type usually determines the numeric coprocessor type
  412.  
  413.   x_mousedriver
  414.   -------------
  415.   C Prototype: extern int x_mousedriver();
  416.  
  417.   This function returns 1 of a mouse driver is installed, 0 otherwise.
  418.   If a mouse driver is detected the mouse related variable (above) are
  419.   set accordingly.
  420.  
  421. --------------------------------------------------------------------------
  422. MODULE XFILEIO
  423. --------------------------------------------------------------------------
  424.  
  425.   Handle based file I/O functions.
  426.  
  427.   See any good DOS programming reference for more information on int 21h
  428.   DOS services.
  429.  
  430.   ASM SOURCES
  431.  
  432.     xfileio.asm xfileio.inc model.inc
  433.  
  434.   C HEADER FILE
  435.  
  436.     xfileio.h
  437.  
  438.   EXPORTED MACROS
  439.  
  440.   file access modes
  441.  
  442.     F_RDONLY
  443.     F_WRONLY
  444.     F_RDWR
  445.  
  446.   seek codes
  447.  
  448.     SEEK_START
  449.     SEEK_CURR
  450.     SEEK_END
  451.  
  452.   file error value
  453.  
  454.     FILE_ERR
  455.  
  456.   EXPORT FUNCTIONS
  457.  
  458.   f_open
  459.   ------
  460.   C Prototype: extern int f_open(char * filename, char access);
  461.  
  462.   Opens a file according to the access char:
  463.  
  464.     F_RDONLY = read only   - If doesnt exist return error
  465.     F_WRONLY = write only  - If doesnt exist create it otherwise clear it
  466.     F_RDWR   = read/write  - If doesnt exist create it
  467.  
  468.   Returns the file handle on success, FILE_ERR on failure
  469.  
  470.  
  471.   f_close
  472.   -------
  473.  
  474.   C Prototype:  extern int f_close(int handle);
  475.  
  476.   Closes the file associated with the specified handle
  477.  
  478.   Returns 0 on success, FILE_ERR on failure
  479.  
  480.  
  481.   f_read
  482.   ------
  483.  
  484.   C Prototype:
  485.  
  486.     extern int f_read(int handle,char near * buffer, int count);
  487.  
  488.   Reads a block of count bytes from the file specified by the handle
  489.   into the near buffer
  490.  
  491.   Returns count on success, FILE_ERR on failure
  492.  
  493.   f_readfar
  494.   ---------
  495.  
  496.   C Prototype:
  497.  
  498.     extern int f_readfar(int handle,char far * buffer, int count);
  499.  
  500.   Reads a block of count bytes from the file specified by the handle
  501.   into the far buffer
  502.  
  503.   Returns count on success, FILE_ERR on failure
  504.  
  505.  
  506.   f_write
  507.   -------
  508.  
  509.   C Prototype: extern int f_write(int handle, char near * buffer, int count);
  510.  
  511.   Writes a block of count bytes to the file specified by the handle
  512.   from the near buffer
  513.  
  514.   Returns count on success, FILE_ERR on failure
  515.  
  516.   f_writefar
  517.   ----------
  518.  
  519.   C Prototype: extern int f_write(int handle, char far * buffer, int count);
  520.  
  521.   Writes a block of count bytes to the file specified by the handle
  522.   from the far buffer
  523.  
  524.   Returns count on success, FILE_ERR on failure
  525.  
  526.  
  527.   f_seek
  528.   ------
  529.  
  530.   C Prototype: extern long int f_seek(int handle, long int position,
  531.                       char method_code)
  532.  
  533.   Moves the file pointer according to the position and method code
  534.  
  535.   Returns file pointer position on success, FILE_ERR on failure
  536.  
  537.  
  538.   f_filelength
  539.   ------------
  540.  
  541.   C Prototype:
  542.  
  543.     extern long int f_filelength(int handle)
  544.  
  545.   Returns the length of the file associated with the specified handle
  546.  
  547.   Returns file length on success, FILE_ERR on failure
  548.  
  549.  
  550.   f_tell
  551.   ------
  552.  
  553.   C Prototype:
  554.  
  555.     extern long int f_tell(int handle)
  556.  
  557.  
  558.   Returns file pointer position on success, FILE_ERR on failure
  559.  
  560. --------------------------------------------------------------------------
  561. MODULE XRLETOOL
  562. --------------------------------------------------------------------------
  563.  
  564. This module implements a number of functions comprising an RLE encoding
  565. decoding system.
  566.  
  567. RLE stands for RUN LENGTH ENCODING. It is a quick simple data compression
  568. scheme which is commonly used for image data compression or compression
  569. of any data. Although not the most efficient system, it is fast, which is
  570. why it is used in image storage systems like PCX. This implementation is
  571. more efficient than the one used in PCX files because it uses 1 bit to
  572. identify a Run Length byte as opposed to two in PCX files, but more on this
  573. later.
  574.  
  575. This set of functions can be used to implement your own compressed image
  576. file format or for example compress game mapse for various levels etc.
  577. The uses are limited by your imagination.
  578.  
  579. I opted for trading off PCX RLE compatibility for the improved compression
  580. efficiency.
  581.  
  582. Here is how the data is un-compressed to give an idea of its structure.
  583.  
  584.  
  585. STEP 1 read a byte from the RLE compressed source buffer.
  586.  
  587. STEP 2 if has its high bit is set then the lower 7 bits represent the number
  588.        of times the next byte is to be repeated in the destination buffer.
  589.        if the count (lower 7 bits) is zero then
  590.       we have finished decoding goto STEP 5
  591.        else goto STEP 4
  592.  
  593. STEP 3 Read a data from the source buffer and copy it directly to the
  594.        destination buffer.
  595.        goto STEP 1
  596.  
  597. STEP 4 Read a data byte from the source buffer and copy it to the destination
  598.        buffer the number of times specified by step 2.
  599.        goto STEP 1
  600.  
  601. STEP 5 Stop, decoding done.
  602.  
  603. If the byte does not have the high bit set then the byte itself is transfered
  604.  to the destination buffer.
  605.  
  606. Data bytes that have the high bit already set and are unique in the input
  607.  stream are represented as a Run Length of 1 (ie 81 which includes high bit)
  608.  followed by the data byte.
  609.  
  610. If your original uncompressed data contains few consecutive bytes and most
  611. have high bit set (ie have values > 127) then your so called
  612. compressed data would require up to 2x the space of the uncompressed data,
  613. so be aware that the compression ratio is extremely variable depending on the
  614. type of data being compressed.
  615.  
  616. Apologies for this poor attempt at a description, but you can look up
  617. RLE in any good text. Alternatively, any text that describes the PCX file
  618. structure in any depth should have a section on RLE compression.
  619.  
  620.  
  621.  
  622.   ASM SOURCES
  623.  
  624.     xrletool.asm xrletool.inc model.inc
  625.  
  626.   C HEADER FILE
  627.  
  628.     xrletool.h
  629.  
  630.   EXPORTED MACROS
  631.  
  632.  
  633.   EXPORT FUNCTIONS
  634.  
  635.   x_buff_RLDecode
  636.   ---------------
  637.  
  638.    Expands an RLE compresses source buffer to a destination buffer.
  639.    returns the size of the resultant uncompressed data.
  640.  
  641.    C PROTOTYPE:
  642.  
  643.    extern unsigned int x_buff_RLDecode(char far * source_buff,
  644.                       char far * dest_buff);
  645.  
  646.    source_buff   - The buffer to compress
  647.    dest_buff     - The destination buffer
  648.  
  649.    WARNING: buffers must be pre allocated.
  650.  
  651.  
  652.    x_buff_RLEncode
  653.    ---------------
  654.  
  655.    RLE Compresses a source buffer to a destination buffer and returns
  656.    the size of the resultant compressed data.
  657.  
  658.    C PROTOTYPE:
  659.  
  660.     extern unsigned int x_buff_RLEncode(char far * source_buff,
  661.          char far * dest_buff,unsigned int count);
  662.  
  663.    source_buff   - The buffer to compress
  664.    dest_buff     - The destination buffer
  665.    count         - The size of the source data in bytes
  666.  
  667.    WARNING: buffers must be pre allocated.
  668.  
  669.    x_buff_RLE_size
  670.    ---------------
  671.  
  672.    Returns the size the input data would compress to.
  673.  
  674.    C PROTOTYPE:
  675.  
  676.     extern unsigned int x_buff_RLE_size(char far * source_buff,
  677.          unsigned int count);
  678.  
  679.    source_buff   - The uncompressed data buffer
  680.    count         - The size of the source data in bytes
  681.  
  682.  
  683.    x_file_RLEncode
  684.    ---------------
  685.  
  686.    RLE Compresses a source buffer to an output file returning
  687.    the size of the resultant compressed data or 0 if it fails.
  688.  
  689.    C PROTOTYPE:
  690.  
  691.    extern unsigned int x_file_RLEncode(int handle,
  692.      char far * source_buff,unsigned int count);
  693.  
  694.    source_buff   - The buffer to compress
  695.    handle        - The file handler
  696.    count         - The size of the source data in bytes
  697.  
  698.    x_file_RLDecode
  699.    ---------------
  700.  
  701.    Expands an RLE compresses file to a destination RAM buffer.
  702.    returns the size of the resultant uncompressed data.
  703.  
  704.    C PROTOTYPE:
  705.  
  706.     extern unsigned int x_buff_RLDecode(int handle,
  707.          char far * dest_buff);
  708.  
  709.    handle        - Input file handle
  710.    dest_buff     - The destination buffer
  711.  
  712.  
  713.  
  714.  
  715. --------------------------------------------------------------------------
  716. MODULE XPOLYGON
  717. --------------------------------------------------------------------------
  718.  
  719.   This module implements eneral filled convex polygon and triangle
  720.   functions
  721.  
  722.   C HEADER FILE
  723.  
  724.     xpolygon.h
  725.  
  726.   TYPE DEFS
  727.  
  728.   typedef struct {
  729.     int X;
  730.     int Y;
  731.   } far VERTEX;
  732.  
  733.  
  734.  
  735.   EXPORT FUNCTIONS
  736.  
  737.  
  738.   x_triangle
  739.   ------------
  740.   C Prototype:
  741.  
  742.   void x_triangle(int x0, int y0, int x1, int y1, int x2, int y2,
  743.          WORD color, WORD PageBase);
  744.  
  745.   This function draws a filled triangle which is clipped to the current
  746.   clipping window defined by TopClip,BottomClip,LeftClip,RightClip.
  747.   Remember: the X clipping variable are in BYTES not PIXELS so you
  748.     can only clip to 4 pixel byte boundaries.
  749.  
  750.  
  751.   x_polygon
  752.   ---------
  753.  
  754.   C Prototype:
  755.  
  756.   void x_polygon(VERTEX *vertices, int  num_vertices,
  757.          WORD color, WORD PageBase);
  758.  
  759.   This function is similar to the triangle function but draws
  760.   convex polygons. The vertices are supplied in the form of a FAR
  761.   pointer.
  762.  
  763.   NOTE: a convex polygon is one such that if you draw a line from
  764.   any two vertices, every point on that line will be within the
  765.   polygon.
  766.  
  767.   This function works by splitting up a polygon into its component
  768.   triangles and calling the triangle routine above to draw each one.
  769.   Performance is respectable but a custom polygon routine might be
  770.   faster.
  771.  
  772. --------------------------------------------------------------------
  773. REFERENCE SECTION
  774. --------------------------------------------------------------------
  775.  
  776.  
  777. REFERENCES
  778. ----------
  779.  
  780. In my opinion Doctor Dobbs Journal is the best reference text for
  781. VGA Mode X graphics:
  782.  
  783. Issue 178 Jul 1991 : First reference to Mode X
  784. Article Abstract   : VGA's undocumented Mode X supports page flipping,
  785.              makes off screen memory available, has square pixels,
  786.              and increases performance by as muck as 4 times.
  787.  
  788. Issue 179 Aug 1991 : Continuation
  789. Article Abstract   : Michael discusses latches and VGA's undoccumented
  790.              Mode X.
  791.  
  792. Issue 181 Sep 1991 : Continuation
  793. Article Abstract   : Michael puts the moves on animation using VGA's 256
  794.              colors.
  795.  
  796. Issue 184 Oct 1991 : First of a continuing series covering 3-D animation
  797.              using VGA's Mode X. This series is still ongoing
  798.              (October 1992)
  799. Article Abstract   : Michael moves into 3-D animation, starting with basic
  800.              polygon fills and page flips.
  801.  
  802.  
  803. WHAT IS MODE X ?
  804. ----------------
  805.  
  806. Mode X is a derrivative of the VGA's standard mode 13h (320x200 256 color).
  807. It is a (family) of undocumented video modes that are created by tweaking
  808. the VGA's registers. The beauty of mode X is that it offers several
  809. benefits to the programmer:
  810.  - Multiple graphice pages where mode 13h doesn't allowing for page flipping
  811.    (also known as double buffering) and storage of images and data in
  812.    offscreen video memory
  813.  - A planar video ram organization which although more difficult to program,
  814.    allows the VGA's plane-oriented hardware to be used to process pixels in
  815.    parallel, improving performance by up to 4 times over mode 13h
  816.  
  817.    See issue 178-179 of D.D.J. for a full description of VGA's Mode X.
  818.  
  819. WHAT IS A SPLIT SCREEN ?
  820. ------------------------
  821.  
  822. A split screen is a neat hardware feature offered by the EGA and VGA video
  823. cards. A split screen is a mode of graphics operationin which the Hardware
  824. splits the visual graphics screen horizontally and treats both halves as
  825. individual screens each starting at different locations in video RAM.
  826.  
  827. The bottom half (which is usually referred to as the split screen) always
  828. starts at address A000:0000 but the top half's starting address is user
  829. definable.
  830.  
  831. The most common application of split screens in games is the status display
  832. in scrolling games. Split screens make this sort of game simpler to program
  833. because when the top half window is scrolled the programmer does not have to
  834. worry about redrawing the bottom half.
  835.  
  836. WHAT IS DOUBLE BUFFERING ?
  837. --------------------------
  838.  
  839. Double buffering (also known as page flipping) is the technique most often
  840. used to do animation. it requires hardware that is capable of displaying
  841. multiple graphics pages (or at least 2). Animation is achieved by drawing
  842. an image in the non visible screen and then displaying the non visible
  843. screen. Once the page has been flipped the process starts again. The next
  844. frame of the animation is drawn on the non visible screen, the page is
  845. flipped again etc.
  846.  
  847. WHAT IS MODE X ?
  848. ----------------
  849.  
  850. Mode X is a derrivative of the VGA's standard mode 13h (320x200 256 color).
  851. It is a (family) of undocumented video modes that are created by tweaking
  852. the VGA's registers. The beauty of mode X is that it offers several
  853. benefits to the programmer:
  854.  - Multiple graphice pages where mode 13h doesn't allowing for page flipping
  855.    (also known as double buffering) and storage of images and data in
  856.    offscreen video memory
  857.  - A planar video ram organization which although more difficult to program,
  858.    allows the VGA's plane-oriented hardware to be used to process pixels in
  859.    parallel, improving performance by up to 4 times over mode 13h
  860.  
  861.    Again see D.D.J. for an in depth discussion of animation using Mode X.
  862.  
  863.    -----------------------------------------------------------------------
  864.  
  865.  
  866.